00. 사전 준비 (환경 설치)

00. 사전 준비: 실습 환경 설치

1주차 수업 전까지 꼭 완료해 주세요

수업 1시간 안에 설치까지 하면 실습할 시간이 없습니다. 아래 [5. 최종 점검] 까지 마치고 오시면 됩니다.
막히는 부분은 7. 자주 나는 문제를 먼저 보시고, 그래도 안 되면 김수종 책임에게 미리 알려주세요.

준비할 것 한눈에 보기

순서 할 일 소요 시간
1 Docker Hub 계정 만들기 3분
2 Docker Desktop 설치 (macOS / Windows) 10~20분
3 Docker Desktop 로그인 · 기본 설정 3분
4 터미널 · 에디터 준비 5분
5 최종 점검 명령어 실행 3분
6 실습 이미지 미리 받아두기 3분

노트북 사양 기준

항목 최소 권장
메모리(RAM) 8GB 16GB 이상 (6주차부터 Kubernetes 노드 여러 개를 띄웁니다)
디스크 여유 공간 20GB 40GB 이상
macOS 최신 및 직전 2개 메이저 버전 Apple Silicon(M 시리즈) / Intel 모두 가능
Windows Windows 10 22H2(빌드 19045) 이상 / Windows 11 23H2(빌드 22631) 이상, 64비트 Windows 11 최신

1. Docker Hub 계정 만들기

Docker Hub 는 컨테이너 이미지를 올리고 내려받는 공개 저장소입니다. 앱스토어 같은 곳이라고 생각하면 됩니다.

  1. https://hub.docker.com 에 접속해서 Sign up 을 누릅니다.
  2. 개인(Personal, 무료) 계정으로 가입합니다.
  3. 가입한 Docker ID(사용자 이름) 를 메모해 둡니다. 4주차에 이미지를 올릴 때 씁니다.
왜 계정이 꼭 필요한가요?

Docker Hub 는 로그인하지 않으면 IP 하나당 6시간에 100번까지만 이미지를 받을 수 있습니다.
회의실에서는 모두 같은 인터넷(같은 공인 IP)을 쓰므로 이 100번을 참석자 전원이 나눠 쓰게 됩니다.
로그인하면 계정마다 6시간에 200번까지 받을 수 있어서 실습에 충분합니다.


2. Docker Desktop 설치

Docker Desktop 이 뭔가요?

컨테이너는 원래 리눅스 커널 기능입니다. 그래서 macOS 와 Windows 에서는 바로 실행할 수 없습니다.
Docker Desktop 은 내 PC 안에 아주 가벼운 리눅스 VM 을 자동으로 띄우고, 그 안에서 컨테이너를 실행해 줍니다.
여기에 Docker 명령어 도구(CLI), Docker Compose, Kubernetes 까지 한 번에 들어 있습니다.

라이선스

Docker Desktop 은 직원 250명 미만, 그리고 연 매출 1,000만 달러 미만인 회사라면 무료로 쓸 수 있습니다. 우리 회사는 여기에 해당합니다.

2-1. macOS

방법 A. 설치 파일 (권장)

  1. https://docs.docker.com/desktop/setup/install/mac-install/ 에 접속합니다.
  2. 내 Mac 칩에 맞는 파일을 받습니다.
    • 확인 방법: 화면 왼쪽 위 메뉴 → 이 Mac에 관하여 → "칩" 항목
    • Apple M1/M2/M3/M4… → Docker Desktop for Mac with Apple silicon
    • Intel → Docker Desktop for Mac with Intel chip
  3. 받은 Docker.dmg 를 열고, Docker 아이콘을 Applications(응용 프로그램) 폴더로 끌어다 놓습니다.
  4. 응용 프로그램에서 Docker 를 실행합니다.
  5. 약관(Subscription Service Agreement) 화면에서 Accept 를 누릅니다.
  6. 설정 화면이 나오면 Use recommended settings 를 선택하고 계속 진행합니다. 관리자 암호를 물어볼 수 있습니다.

방법 B. Homebrew 를 쓰는 분

brew install --cask docker-desktop

설치가 끝나면 응용 프로그램에서 Docker 를 한 번 실행하고, 약관에 동의해 주세요.

Apple Silicon Mac 이라면 (선택)

Rosetta 2 를 설치해 두면, 인텔(amd64)용 도구가 필요할 때 문제가 줄어듭니다.

softwareupdate --install-rosetta --agree-to-license

2-2. Windows

① WSL 2 준비 (Docker Desktop 은 WSL 2 위에서 리눅스를 돌립니다)

PowerShell 을 관리자 권한으로 엽니다(시작 메뉴 → "PowerShell" 우클릭 → 관리자 권한으로 실행).

# WSL 이 없으면 설치, 있으면 그대로 진행됩니다
wsl --install --no-distribution

# WSL 을 최신으로 업데이트
wsl --update

# 버전 확인: "WSL 버전" 이 2.1.5 이상이면 OK
wsl --version

출력 예시:

WSL 버전: 2.6.3.0
커널 버전: 6.6.87.2-1
...
wsl --install 을 처음 실행했다면

PC 를 재부팅한 뒤 다음 단계로 넘어가세요.

② Docker Desktop 설치

  1. https://docs.docker.com/desktop/setup/install/windows-install/ 에서 Docker Desktop for Windows - x86_64 를 받습니다.
    • ARM 노트북(Snapdragon 등)이라면 Arm (Early Access) 버전을 받습니다. 아직 시험판이라 문제가 생기면 알려주세요.
  2. Docker Desktop Installer.exe 를 실행합니다.
  3. 설치 옵션은 기본값 그대로 둡니다.
    • 설치 방식은 사용자 단위 설치(Per-user) 가 기본이라 관리자 권한이 필요 없습니다.
    • 백엔드는 WSL 2 를 사용합니다.
  4. 설치가 끝나면 Close 를 누르고, 시작 메뉴에서 Docker Desktop 을 실행합니다.
  5. 약관 화면에서 Accept 를 누릅니다.
winget 을 쓰는 분

winget install -e --id Docker.DockerDesktop

설치 중에 관리자 권한(UAC) 창이 뜨면 예를 누르세요.

Windows 는 Docker Desktop 이 자동으로 시작되지 않을 수 있습니다

실습 전에 시작 메뉴에서 Docker Desktop 을 직접 실행하세요.
작업 표시줄 오른쪽 아래에 고래 아이콘이 보이고, 대시보드 왼쪽 아래에 Engine running 이 보이면 준비된 것입니다.


3. Docker Desktop 로그인 · 기본 설정

3-1. 로그인 (macOS / Windows 동일)

  1. Docker Desktop 오른쪽 위의 Sign in 을 누릅니다.
  2. 브라우저가 열리면 1단계에서 만든 계정으로 로그인합니다.
  3. Docker Desktop 오른쪽 위에 내 아이디가 보이면 완료입니다.
로그인해야 하는 이유

  • Docker Hub pull 제한이 IP 공용 한도가 아니라 내 계정 기준(6시간에 200회) 으로 바뀝니다.
  • 4주차에 내가 만든 이미지를 Docker Hub 에 올릴(push) 때도 로그인이 필요합니다.

3-2. 메모리 할당 확인

6주차부터 Kubernetes 를 띄우면 메모리를 꽤 씁니다. 지금은 확인만 해 두세요.

OS 확인 위치 권장
macOS Docker Desktop → Settings(⚙️) → Resources → Memory 노트북 RAM 의 절반 정도 (16GB 노트북이면 8GB)
Windows (WSL 2) 따로 설정하지 않아도 됩니다. 기본으로 PC 메모리의 50% 까지 사용합니다. 기본값 유지

4. 터미널 · 에디터 준비

4-1. 터미널

OS 사용할 터미널 주의
macOS 기본 터미널 앱 (또는 iTerm2). 셸은 zsh -
Windows PowerShell (Windows Terminal 안의 PowerShell 도 OK) Git Bash 는 쓰지 마세요
Windows 에서 Git Bash 를 쓰면 안 되는 이유 (실제로 확인한 문제)

Git Bash 는 /etc/os-release 같은 리눅스 경로를 Windows 경로로 몰래 바꿔서 Docker 에 넘깁니다.

$ docker run --rm alpine:3.24 cat /etc/os-release
cat: can't open 'C:/Program Files/Git/etc/os-release': No such file or directory

PowerShell 에서는 이런 문제가 없습니다. 이 스터디의 Windows 명령어는 모두 PowerShell 기준입니다.

4-2. 에디터: VS Code (권장)

  1. https://code.visualstudio.com 에서 설치합니다.
  2. 왼쪽 확장(Extensions) 메뉴에서 아래 두 개를 설치합니다.
확장 이름 만든 곳 용도
Container Tools Microsoft 컨테이너 · 이미지 목록 보기, Dockerfile 자동완성
Docker DX Docker Dockerfile · Compose 파일 오류 검사

6주차에 Kubernetes 확장을 추가로 안내합니다.


5. 최종 점검

터미널(macOS: 터미널 / Windows: PowerShell)을 열고 아래 명령어를 하나씩 실행합니다.

5-1. 버전 확인

docker version

출력 예시: Client 와 Server 가 둘 다 나와야 정상입니다.

Client:
 Version:           29.8.1
 ...
Server: Docker Desktop 4.93.0 (240920)
 Engine:
  Version:          29.8.1
 ...
Server 부분에 에러가 나온다면

failed to connect to the docker API ... 같은 메시지가 보이면 Docker Desktop 이 실행되지 않은 상태입니다. Docker Desktop 을 실행하고 1분쯤 기다린 뒤 다시 시도하세요.

docker compose version

출력 예시:

Docker Compose version v5.5.1

5-2. 첫 컨테이너 실행

docker run --rm hello-world

출력 예시: 아래 문장이 보이면 설치 성공입니다. 🎉

Hello from Docker!
This message shows that your installation appears to be working correctly.

5-3. Docker Hub 로그인 확인

docker login

6. 실습 이미지 미리 받아두기

회의실 네트워크가 몰리지 않도록 1~2주차에 쓸 이미지를 미리 받아 둡니다.

docker pull hello-world
docker pull alpine:3.24
docker pull ubuntu:26.04
docker pull nginx:1.30-alpine

받은 이미지를 확인합니다.

docker image ls

출력 예시:

IMAGE               ID             DISK USAGE   CONTENT SIZE   EXTRA
alpine:3.24         294b683cb724         13MB         3.94MB
hello-world:latest  5e2309035332       25.9kB         9.49kB
nginx:1.30-alpine   0985e772fb9f       93.6MB           27MB
ubuntu:26.04        da6fc2be5478        160MB         45.3MB

ID 와 용량은 사람마다 조금 다를 수 있습니다. 4개가 모두 보이면 준비 끝입니다. ✅


7. 자주 나는 문제와 해결

공통

증상 원인 해결
failed to connect to the docker API Docker Desktop 이 꺼져 있음 Docker Desktop 실행 후 Engine running 확인
toomanyrequests: You have reached your pull rate limit Docker Hub 비로그인 상태로 너무 많이 받음 3-1. 로그인 후 다시 시도
Bind for 0.0.0.0:8080 failed: port is already allocated 다른 프로그램이 같은 포트를 쓰는 중 1주차에서 설명합니다. 다른 포트 번호(예: 8081)를 쓰면 됩니다

Windows

증상 해결
설치 중 "WSL 2 is not installed" / "WSL update required" 관리자 PowerShell 에서 wsl --update 실행 후 재부팅
"Virtualization support not detected" BIOS/UEFI 에서 가상화(Intel VT-x / AMD-V, SVM) 를 켜야 합니다. 노트북마다 메뉴가 다르니 문의해 주세요
업데이트 후 "WSL integration with distro 'Ubuntu' unexpectedly stopped" 창이 계속 뜸 아래 순서대로 하세요 ⬇️

WSL integration 오류가 반복될 때 (실제로 겪고 해결한 방법)

# 1) 작업 표시줄의 고래 아이콘 우클릭 → Quit Docker Desktop 으로 완전히 종료
# 2) WSL 을 완전히 내림 (열려 있는 Ubuntu 창이 있으면 같이 닫힙니다)
wsl --shutdown
# 3) 시작 메뉴에서 Docker Desktop 다시 실행

Ubuntu 같은 WSL 배포판을 쓰지 않는다면, 창의 Skip WSL distro integration 을 눌러도 이 스터디 실습에는 지장이 없습니다.

macOS

증상 해결
docker: command not found Docker Desktop 을 한 번도 실행하지 않은 경우입니다. 응용 프로그램에서 Docker 를 실행하고 약관에 동의하세요
Docker Desktop 이 멈춘 듯 시작이 안 됨 메뉴 막대 고래 아이콘 → Troubleshoot → Restart Docker Desktop

참고 자료

공식 문서:


네비게이션

목록 다음
목록으로 1주차 강의 노트 ▶